<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
  <title>PodofoImpose - some words</title>
  <meta name="AUTHOR" content="Pierre Marchand"/>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <style type="text/css">
body{
	width:360pt;
	margin:auto;
	font-family:sans-serif;
	font-size:11.2pt;
}
.section{
/* 	background-color:#ddd; */
	border-left:1pt solid #333;
	padding-left:12pt;
	
}
.code-abs{
	font-family:mono;
	font-weight:bold;
	font-size:9pt;
	background-color:#eee;
	color:#222;
}
.command{
	font-family:monospace;
	font-size:9pt;
	background-color:#222;
	color:#eee;
	padding:6pt;
}
.file{
	border:1pt dotted black;
	width:90%;
	margin:12pt auto;
}
.file .name{
	text-align:right;
	font-family:monospace;
	font-weight:bold;
	font-size:8pt;
	background-color:#eee;
}
.file .content{
	margin:0;
	padding:0;
	border:0;
	white-space:pre;
}
  </style>
</head>
<body>
	<h2>PodofoImpose</h2>
	<div id="intro">PodofoImpose is a utility program which aims to provide a rather simple way to impose PDF documents. Originally written for my own use, it ended up in PoDoFo release as a show-case (don’t rely too much on it).
	</div>
	
	<h3>Plan (built-in)</h3>
	<div class="section"><!-- Plan own -->
		PodofoImpose is driven by a PLAN file. This file describes how pages from a source PDF document have to be relayout into a target document. We’ll describe how this file must be formated.
		<h4>Records</h4>
		<div>
			Most of the PLAN file is composed of record lines of the form:
			<div class="code-abs">
				source page; target page; rotation; horizontal translation; vertical translation;
			</div>
			Each element of the record can be a numeric value, a constant or an expression involving both numerics and constants.
		</div>
		<h4>Constants</h4>
		<div>
			Constants can be  declared everywhere in the PLAN file except in loops. They are 8 bits char strings (except "=") with a leading "$" character which makes them easy to identify. Their value is always interpreted as a float through std::atof. You can "overload" a constant value by redeclaring it. They are declared in this form:
			<div class="code-abs">
				$MyConstant = 123.456
			</div>
			Note that a PLAN file is valid only if it contains 2 required constants which are "$PageWidth" and "$PageHeight", giving target document dimensions. Now support the "$ScaleFactor" constant -- means that the declared scale factor will be added to the current transformation matrix for each placed page. Constants declarations can hold expressions:
			<div class="code-abs">
				$MyConstant = $AnotherConst * .5;
			</div>
			Source document pages count is provided as "$PageCount".
			Source first page geometry is provided as "$SourceWidth" and "$SourceHeight", reflecting geometry given by the MediaBox.
		</div>
		<h4>Expressions</h4>
		<div>
			An expression is a set of basic mathematic operations +, -, *,/ and % (operands of modulo will be first rounded). As a convenience, we added the | as "max(a,b)" it’s mainly there to allow user to prevent division by 0.
			<div class="code-abs">
				$ValueA / ( $ValueB | 0.000001 )
			</div>
 			Operations are executed from left to right without taking care of any kind of precedance. You can use parenthesis to enclose operations that need to be computed separetly. Example:
			<div class="code-abs">
				123.456 * ( $ConstantA - ( $ConstantB / 3.14 ) )
			</div>
		</div>
		<h4>Loops</h4>
		<div>
			Loops allow users to programmatically generate records. While the concept itself is familiar to programmers I can imagine that regular users would feel not so easy with it. So let me introduce a simple example to explain the thing.
		</div>
		<div>
			Let say we have a source document, A4 format, which has 1000 pages and we just want to position each page of the first half of the document on the center of an A3 plate.
			<div class="file">
				<div class="name">A4onA3.plan</div>
				<div class="content">$PageWidth=842.6 
$PageHeight=1195.2
## SourceWidth &#38; SourceHeight
$sw=597.6
$sh=842.4
$page=1
&#60;$PageCount/2[$page+1]
$page; $page; 0; ($PageWidth-$sw)/2; ($PageHeight-$sh)/2;
&#62;
</div>	
			</div>
			The loop is what’s enclosed by "&#60;" and "&#62;"characters, the second just indicates the end of the loop. The first first indicates how many iterations (loops) have to be performed &#8212; 500 here. Then comes the interesting part, constants which appear in parenthesis will be incremented by the value following the "+" (can be a minus one, in that case don’t turn the "+" into a "-", just prefix the value with "-" as in [$foo+-1.23]), which means in this example that at each iteration, $page will see its value increased by 1.
		</div>
		<div>
			Constants (which finally turn into variables ;-)) must be declared before the loop. Many constants can be put in loop declaration, separate them with semicolons.
		</div>
		<div>
			<!-- No, loops can’t be nested! -->
			There is an experimental support of nested loops.
		</div>
		<h4>Running</h4>
		<div>
		Once you’ve wrote the PLAN file you can run the program: 
			<div class="command">
				podofoimpose source.pdf target.pdf plan.plan
			</div>
		Note the source can be either a PDF file or a text file which is a listing of PDF files. In this case, listed files will be first merged in order.
		</div>
        </div> <!-- Plan -->
	  <h3>Plan (Lua)</h3>
	<div class="section"><!-- lua plan -->
	    PoDoFoImpose now supports Lua scripted plan files. Note that, mainly for security reasons, only the following modules are loaded: base, table, string, math. If you need more, just add luaopen_* calls to LuaMachina::LuaMachina().
	    <h4>Format</h4>
	    <div>
	     Records are pushed with:
	     <div class="command">
	      PushRecord(source page, target page, rotation, x, y);
	      </div>
		As for regular plan files, there are a couple of provided informations through global variables, specifically: "SourceWidth", "SourceHeight", "PageCount". You need to set "PageWidth" and "PageHeight". You may alter the global scale factor (from source to target) by setting "Scale".
	     </div>
		<h4>Running</h4>
		 <div>
		  There is no format detection mechanism, so you need to append "lua" keyword to podofoimpose invocation when you want it to process a Lua script.
		  </div>

	 </div> <!-- lua plan -->
	
	<h3>Examples</h3>
	<div class="section"><!-- Examples -->
	 <div>
	  For Lua scripts, some samples can be found in directory tools/podofoimpose/plans/lua of PoDoFo sources tree.
	  </div>
	<h5>Add a stamp to a document</h5>
	Shame on me, don’t even have a real stamp at my "office". So I tried something and it worked! Say you have that official one page A4 doc, named official.pdf, on which you want to add a nice stamp. You have your stamp in the file stamp.pdf. You first have to create two files:
	<div class="file">
		<div class="name">
		pdf.list
		</div>
		<div class="content">official.pdf
stamp.pdf</div>
	</div>
	<div class="file">
		<div class="name">stamponator.plan</div>
<div class="content">$PageWidth=597.6 
$PageHeight=842.4
# original page is left unchanged;
1; 1; 0; 0; 0;
# positionning stamp is up to you!
2; 1; 0; 350; 100;</div>
	</div>
	Now you can run:
	<div class="command">podofoimpose  pdf.list stamped-official.pdf stamponator.plan</div>

	<h5>Make a tiled poster</h5>
	<div>
		Printing a large graphic onto a set of little paper sheets can be handful. Doing it automatically is even better! <!--You can find files used in this example here: <a href="poster.pdf">poster.pdf</a>,
							 <a href="poster_mask.pdf">poster_mask.pdf</a>,
							  <a href="poster.plan">poster.plan</a> and 
							  <a href="poster.list">poster.list</a>. Here constants are a bit abbreviated in order to fit in the frame.-->
		Latest changes allow us to provide you with a quasi all-automatic solution. The only thing that you would want to change (apart from debugging) is the output paper size (here ISO-A4, "Europe oblige !").
		<div class="file">
			<div class="name">poster.plan</div>
			<div class="content">
##POSTER printed on tiled A4 paper sheets.
# destination (A4)
$PageWidth = 597.6
$PageHeight = 842.4

$sW = $SourceWidth 
$sH = $SourceHeight 

# with a little trick to get integers
$rows = (($sH / $PageHeight) + 1) % (2 * (($sH / $PageHeight)+1))
$cols = (($sW / $PageWidth)  + 1) % (2 * (($sW / $PageWidth )+1))

$hbox = ($sW / ($cols | 1))
$vbox = ($sH/ ($rows | 1))
$hm = ($PageWidth -  $hbox ) / 2
$vm = ($PageHeight - $vbox ) / 2

$R = 1
$C = 1
&#60;$rows[$R+1]
	&#60;$cols[$C+1]
		1; (($R - 1)*$cols) + $C; 0; $hm - (($C -1) * $hbox); $vm - (($R-1) * $vbox);
	&#62;
&#62;

</div>
			</div>
		</div>
	<div class="command">podofoimpose poster.pdf poster_tiled.pdf poster.plan </div>
	<div>Etc.</div>
	</div><!-- Examples -->
</body>
</html>
